feat: expose stratum mining stats via Owner API by iho · Pull Request #3897 · mimblewimble/grin

iho · 2026-07-09T08:34:27Z

Summary

Adds an Owner API endpoint for stratum mining statistics so operators running headless (no TUI) can inspect connected workers and share stats — the same data shown on the TUI mining tab.

Closes #3201

Changes

New get_mining_status method on Owner JSON-RPC (/v2/owner)
New types: MiningStatus / WorkerInfo in the API crate
Server wires live StratumStats into the Owner API via a provider callback
CLI: grin client miningstatus
Brief docs in doc/api/api.md

Example

{
  "jsonrpc": "2.0",
  "method": "get_mining_status",
  "params": [],
  "id": 1
}

Returns whether stratum is enabled/running, worker count, block height, network difficulty/hashrate, blocks found, and per-worker share stats for currently connected workers. When stratum is disabled, a provider still returns is_enabled: false. If no mining stats provider is wired into the Owner API, get_mining_status returns an internal error instead of masking the misconfiguration as disabled.

Test plan

Unit tests: MiningStatus serde roundtrip
Unit tests: Owner::get_mining_status without provider (error) and with provider via generated OwnerRpc JSON-RPC handler (wire response)
Unit tests: StratumStats → MiningStatus conversion (filters disconnected workers)
cargo check -p grin --bin grin
Manually: enable stratum, connect a miner, run grin client miningstatus

wiesche89

This is a nice and useful feature, and the endpoint is wired to the live StratumStats correctly. Before merging, I’d clarify whether the API should return only active workers, avoid masking a missing provider as disabled, and preserve the public node_apis signature.

wiesche89 · 2026-07-12T09:23:18Z

+	/// Whether the stratum server is enabled in config
+	pub is_enabled: bool,
+	/// Whether the stratum server is currently running
+	pub is_running: bool,


The source flag is set on startup but never cleared on listener failure or shutdown. Is “currently running” too strong for the API contract?

A port conflict still leaves this as true after the listener exits. Could we set it after a successful bind, clear it on exit, and test the bind-failure case?

Add get_mining_status to the Owner JSON-RPC API so headless operators can query the same stratum/worker stats shown on the TUI mining tab. Wire live StratumStats into node_apis and add `grin client miningstatus`. Closes mimblewimble#3201

- Filter mining status worker_stats to currently connected workers (StratumStats retains disconnected workers for the node lifetime), and drop the now always-true is_connected field from WorkerInfo - Return an internal error from get_mining_status when no stats provider is wired, instead of masking it as disabled - Restore the public node_apis signature; add node_apis_with_mining_stats for provider wiring - Document is_running as set-once at startup - Trim get_mining_status doc comment to match neighboring methods

wiesche89 · 2026-07-19T14:56:45Z

+			blocks_found: stats.blocks_found,
+			network_hashrate: stats.network_hashrate,
+			minimum_share_difficulty: stats.minimum_share_difficulty,
+			// worker_stats retains every worker that ever connected; only expose


The response is bounded now, but each request still scans the full worker history under the stats lock. Could we keep a bounded active-worker view and derive num_workers from it too?

wiesche89 · 2026-07-19T14:57:35Z

+	/// Whether the stratum server is enabled in config
+	pub is_enabled: bool,
+	/// Whether the stratum server is currently running
+	pub is_running: bool,


A port conflict still leaves this as true after the listener exits. Could we set it after a successful bind, clear it on exit, and test the bind-failure case?

wiesche89 · 2026-07-19T14:58:42Z

+	pub worker_stats: Vec<WorkerInfo>,
+}
+
+impl Default for MiningStatus {


This has no caller besides its own test and duplicates StratumStats::default(). Could we remove the impl and test to avoid default drift?

Removed the Default impl and its unit test so we do not duplicate / drift from StratumStats::default.

wiesche89 · 2026-07-19T14:59:17Z

+	}
+
+	#[test]
+	fn get_mining_status_with_provider() {


Could we test this once through the generated JSON RPC handler? The current tests only call Owner directly, so the wire response is not covered.

Done — get_mining_status is now covered through the generated OwnerRpc JSON-RPC handler (success wire payload + missing-provider error path).

wiesche89 · 2026-07-19T15:00:26Z

+	pub fn get_mining_status(&self) -> Result<MiningStatus, Error> {
+		match &self.mining_stats {
+			Some(provider) => Ok(provider()),
+			None => Err(Error::Internal(


This is fixed now. Could you also update the PR description? It still says a missing provider returns a disabled default.

PR description updated: missing provider returns an internal error; disabled stratum still returns is_enabled: false via the wired provider.

wiesche89 · 2026-07-19T15:19:33Z

I’ve written a prototype Grin miner in Rust https://github.com/wiesche89/rust-miner . It can be used to test the new Owner API method end to end.
With a synced testnet node running, Stratum enabled on port 13416, and the Owner API listening on 13413, start a lightweight worker with:

./target/release/grin-cuckatoo-miner mine \
  --backend cpu \
  --edge-bits 25 \
  --node-port 13416 \
  --login api-test-1

I tested four connected miners this way. The API reported num_workers: 4 with four worker entries, then returned num_workers: 0 and an empty worker list after disconnecting them. C25 is only intended as a lightweight connection test, valid testnet mining requires C32.

Remove the unused MiningStatus Default impl (and its test) to avoid drift from StratumStats::default. Cover get_mining_status through the generated OwnerRpc JSON-RPC handler so the wire response is tested.

wiesche89 reviewed Jul 12, 2026

View reviewed changes

feat: expose stratum mining stats via Owner API

ead8310

Add get_mining_status to the Owner JSON-RPC API so headless operators can query the same stratum/worker stats shown on the TUI mining tab. Wire live StratumStats into node_apis and add `grin client miningstatus`. Closes mimblewimble#3201

iho force-pushed the feat/mining-status-api branch 2 times, most recently from f406b85 to 60178eb Compare July 17, 2026 00:56

iho force-pushed the feat/mining-status-api branch from 60178eb to 120e0cd Compare July 17, 2026 00:58

iho requested a review from wiesche89 July 17, 2026 01:01

wiesche89 reviewed Jul 19, 2026

View reviewed changes

Address remaining review feedback on mining status API

336e48a

Remove the unused MiningStatus Default impl (and its test) to avoid drift from StratumStats::default. Cover get_mining_status through the generated OwnerRpc JSON-RPC handler so the wire response is tested.

iho requested a review from wiesche89 July 25, 2026 17:18

Uh oh!

Conversation

iho commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Example

Test plan

Uh oh!

wiesche89 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wiesche89 commented Jul 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

iho commented Jul 9, 2026 •

edited

Loading